Skip to content

feat(usage): add opt-in signed usage receipts - #68

Merged
ALikesToCode merged 4 commits into
feat/learned-cooldownfrom
feat/usage-receipts
Oct 9, 2026
Merged

ALikesToCode merged 4 commits into
feat/learned-cooldownfrom
feat/usage-receipts

Conversation

@ALikesToCode

Copy link
Copy Markdown
Owner

Summary

Adds opt-in signed usage receipts. Each settled usage event can get an Ed25519-signed, hash-chained receipt per principal, which its owner can fetch and verify. Receipts prove that the gateway signed a usage record. They don't prove what the provider billed. With USAGE_RECEIPTS_ENABLED unset or off (the default), the usage ledger, its storage and every response are byte-for-byte unchanged.

  • Settings:
    • USAGE_RECEIPTS_ENABLED: empty means off; a malformed value is off with one warning that leaves the value out.
    • USAGE_RECEIPTS_KEY_ID names the active key.
    • USAGE_RECEIPTS_SIGNING_KEY_REF names the environment variable or Worker secret binding that holds the base64 PKCS#8 Ed25519 private key; it never holds the key itself.
    • Responses and errors never include key material.
  • Keys: operators review a public key and insert it into usage_receipt_keys with reviewed=1. Unreviewed or mismatched keys don't sign. Rotated-out keys stay published so old receipts remain verifiable.
  • Receipts:
    • Each receipt holds {record, canonical_bytes_base64, signature_ed25519, key_id, previous_hash, record_hash, sequence}.
    • The canonical JSON keeps every unknown field and exact null, and writes numbers as exact IEEE-754 decimals. The signed bytes are domain-separated and bind the key ID, principal, event, sequence and previous hash.
    • Unknown and estimated cost stays explicit (cost_usd: null, usage_basis: "unknown").
  • Chain:
    • Sequences start at 1 per principal, and an atomic compare-and-swap advances the head.
    • Each event ID is unique per principal: replaying it returns the same receipt, and different metadata under the same ID returns 409.
    • A correction appends a new linked record and never rewrites the old one.
  • Reads:
    • GET /v1/usage/receipts/<id> is owner-only and returns 404 otherwise, including for administrators.
    • GET /v1/usage/receipt-keys returns reviewed public keys only.
    • Both require the models scope and send Cache-Control: no-store.
  • Failures: with receipts on and the tables, key or runtime support missing, receipt reads and writes return JSON 503. Usage recording continues unchanged, and a receipt failure only logs one fixed warning.
  • Runtimes: Python signs with the installed cryptography package and the Worker with WebCrypto Ed25519. Both test files check the same published RFC 8032 vector and canonical bytes.

Details are in docs/usage-receipts.md.

Wiring

  • services/usage_ledger.py: after a successful flush, the ledger calls usage_receipts.record_flushed_usage(batch_id, rows). This is a no-op while off and absorbs its own errors while on. Event IDs are <batch-id>:<row-index>.
  • worker/usage-ledger-d1.mjs makes the same call after a stored batch. A D1 deployment where both runtimes see the batch produces one receipt per event, because event IDs are unique per principal.
  • worker/managed-state-dispatch.mjs routes the private /v1/managed-state/usage-receipts operation (append/get/keys). It returns 404 while off, accepts only intelligence.internal, and caps requests at 128 KiB.
  • routes/usage_receipts.py exposes register_usage_receipt_routes. Mounting it in app.py, the public Worker routes, the Flask D1 store endpoint and the reservation reconciliation hook come with the Wave 6 integration.

Shared registrations

  • tests/test_usage_receipts_worker.mjs in test:worker.
  • worker/usage-receipts.mjs in the edge module inventory, and both receipt routes in the Flask route inventory.
  • USAGE_RECEIPTS_ENABLED, USAGE_RECEIPTS_KEY_ID and USAGE_RECEIPTS_SIGNING_KEY_REF in the Container env keys.
  • usage_receipt_keys, usage_receipt_heads and usage_receipts in REQUIRED_D1_TABLES.

No browser-readable headers.

Stacked on #67

Migration numbers must be contiguous in each PR, so this branch merges feat/learned-cooldown (#67, migration 0031), which stacks on #66 (0030) and #62 (0029). Merge those first.

Tests

  • tests/test_usage_receipts.py and tests/test_usage_receipts_worker.mjs cover:
    • flag off, empty and malformed leaving the ledger and responses unchanged;
    • the shared canonical and signature vectors;
    • unknown fields, nulls, exact decimals, negative zero and safe integers;
    • chain sequence and previous hash, concurrent compare-and-swap and event deduplication;
    • 409 on conflicting replay, and corrections appending without rewriting;
    • owner-only reads, including administrators;
    • reviewed and rotated keys, and missing or mismatched keys returning 503 while usage recording continues;
    • content and credential field rejection, and size and depth bounds;
    • a real workerd and D1 rehearsal.
  • Full Python suite: 4,549 passed, 2 skipped. ruff, mypy and bandit are clean.
  • npm run test:worker: 1,684 passed. npm run test:integration: 7 passed.
  • cf:migrations:check reports 32 contiguous, additive migrations. test:deploy, free routes, client headers and the wrangler deploy --dry-run bundle all pass.
  • tests/test_frontend_build.mjs fails locally because @tailwindcss/cli is not installed. It fails the same way on main.

Apply the migration before enabling receipts: npx wrangler d1 migrations apply multillm-intelligence --remote.

CI notes

  • GitHub python/node jobs: the dependency-audit steps fail on every branch, including main. fix(deps): clear the CI dependency audit advisories #42 fixes that.
  • Workers Builds: fails on this stack because the Wave 3 base adds the AdmissionCoordinator Durable Object migration, which wrangler versions upload cannot apply. This is expected until wrangler deploy runs on main.

This is part of Wave 6. The README line comes with the Wave 6 integration PR.

@chatgpt-codex-connector

Copy link
Copy Markdown

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, add credits to your account and enable them for code reviews in your settings.

@coderabbitai

coderabbitai Bot commented Oct 9, 2026

Copy link
Copy Markdown

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration
  • Configuration used: defaults
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: 7fbadeec-80b3-40ed-ad33-b28b1d4ec881

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

  • 🔍 Trigger review
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@cloudflare-workers-and-pages

Copy link
Copy Markdown

Deploying with  Cloudflare Workers  Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status Name Latest Commit Updated (UTC)
❌ Deployment failed
View logs
multillm-proxy ec0f357 Oct 09 2026, 05:52 AM

@ALikesToCode
ALikesToCode merged commit ee06f6d into feat/learned-cooldown Oct 9, 2026
4 of 7 checks passed
@ALikesToCode
ALikesToCode deleted the feat/usage-receipts branch October 26, 2026 20:17
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant